<!DOCTYPE html>
<html>

  <head>
    <meta charset='utf-8' />
    <meta http-equiv="X-UA-Compatible" content="chrome=1" />
    <meta name="description" content="CAS - Single Sign-On for the Web" />
    
    
    <link rel="stylesheet" type="text/css" media="screen"
          href="../../stylesheets/v40x-stylesheet.css">
    <link rel="stylesheet" type="text/css" media="print"
          href="../../stylesheets/print.css">
    <title>CAS - CAS REST Protocol</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
    <script src="../../javascripts/URI.js"></script>
    <script src="../../javascripts/v40x-main.js"></script>
  </head>

  <body>
    <!-- HEADER -->
    <div id="header_wrap" class="outer">
        <header class="inner">
          <a id="forkme_banner" href="https://github.com/Jasig/cas">View on GitHub</a>
          <div id="project_title">
            <a class="undecorated" href="../../index.html">
              <img class="undecorated" src="../../images/cas_logo.png"/>
            </a>
          </div>
          <h2 id="project_tagline">Single Sign-On for the Web</h2>
        </header>
    </div>

    <!-- NAVBAR -->    
    <div id="navbar_wrap" class="outer">
      <header id="navbar_content" class="inner">
        <div class="navlink">
  <a href="../../index.html">Home</a>
</div>
<div class="navlink">
  <a href="https://github.com/Jasig/cas/releases">Downloads</a>
</div>
<div class="navlink">
  <a href="https://www.google.com/cse/publicurl?cx=017040929083740828958:sqr2hwvrxmg">Search</a>
</div>
<div class="navlink">
  <a href="../../Support.html">Support</a>
</div>
<div class="navlink">
  <a href="../../Mailing-Lists.html">Mailing Lists</a>
</div>
<div class="navlink">
  <a href="../../Older-Versions.html">Older Versions</a>
</div>

        </header>
    </div>

      <!-- SIDEBAR -->
      <div id="sidebar_wrap" class="outer">
        <header id="sidebar_content" class="inner">
          <span id="sidebartoc"></span>
        </header >
      </div>
      
      <!-- PAGE TABLE OF CONTENTS -->
      <div id="table_contents" class="outer">
        <header id="sidebar_content" class="inner">
          <span id="tableOfContents"></span>
        </header>
      </div>
      
      <!-- MAIN CONTENT -->
      <div id="main_content_wrap" class="outer">
        <section id="main_content" class="inner">
          <h1 id="rest-protocol">REST Protocol</h1>
<p>The REST protocol allows one to model applications as users, programmatically acquiring service tickets to authenticate to other applications. This means that other applications would be able to use a CAS client  to accept Service Tickets rather than to rely upon another technology such as client SSL certificates for application-to-application authentication of requests. This is achieved by exposing a way to RESTfully obtain a Ticket Granting Ticket and then use that to obtain a Service Ticket.</p>

<div class="alert alert-warning"><strong>Usage Warning!</strong><p>The REST endpoint may become a tremendously convenient target for brute force dictionary attacks on CAS server. Enable support only soberly and with due consideration of security aspects.</p></div>

<h1 id="components">Components</h1>
<p>By default the CAS RESTful API is configured in the <code>restlet-servlet.xml</code>, which contains the routing for the tickets. It also defines the resources that will resolve the URLs. The <code>TicketResource</code> defined by default (which can be extended) accepts username/password.</p>

<p>Support is enabled by including the following in your <code>pom.xml</code> file:</p>

<pre><code>&lt;dependency&gt;
    &lt;groupId&gt;org.jasig.cas&lt;/groupId&gt;
    &lt;artifactId&gt;cas-server-integration-restlet&lt;/artifactId&gt;
    &lt;version&gt;${cas.version}&lt;/version&gt;
&lt;/dependency&gt;
</code></pre>

<p>REST support is currently provided internally by the <a href="http://restlet.org/‎">Restlet framework</a>.</p>

<h1 id="configuration">Configuration</h1>
<p>To turn on the protocol, add the following to the <code>web.xml</code>:</p>

<div class="highlight"><pre><code class="xml"><span class="nt">&lt;servlet&gt;</span>
    <span class="nt">&lt;servlet-name&gt;</span>restlet<span class="nt">&lt;/servlet-name&gt;</span>
    <span class="nt">&lt;servlet-class&gt;</span>org.restlet.ext.spring.RestletFrameworkServlet<span class="nt">&lt;/servlet-class&gt;</span>
    <span class="nt">&lt;load-on-startup&gt;</span>1<span class="nt">&lt;/load-on-startup&gt;</span>
<span class="nt">&lt;/servlet&gt;</span>
 
<span class="nt">&lt;servlet-mapping&gt;</span>
    <span class="nt">&lt;servlet-name&gt;</span>restlet<span class="nt">&lt;/servlet-name&gt;</span>
    <span class="nt">&lt;url-pattern&gt;</span>/v1/*<span class="nt">&lt;/url-pattern&gt;</span>
<span class="nt">&lt;/servlet-mapping&gt;</span>
</code></pre></div>

<h1 id="protocol">Protocol</h1>

<h2 id="request-a-ticket-granting-ticket">Request a Ticket Granting Ticket</h2>

<h3 id="sample-request">Sample Request</h3>

<div class="highlight"><pre><code class="bash">POST /cas/v1/tickets HTTP/1.0
 
<span class="nv">username</span><span class="o">=</span>battags<span class="p">&amp;</span><span class="nv">password</span><span class="o">=</span>password<span class="p">&amp;</span><span class="nv">additionalParam1</span><span class="o">=</span>paramvalue
</code></pre></div>

<h3 id="sample-response">Sample Response</h3>

<h4 id="successful-response">Successful Response</h4>

<div class="highlight"><pre><code class="bash">201 Created
Location: http://www.whatever.com/cas/v1/tickets/<span class="o">{</span>TGT id<span class="o">}</span>
</code></pre></div>

<h4 id="unsuccessful-response">Unsuccessful Response</h4>
<p>If incorrect credentials are sent, CAS will respond with a 400 Bad Request error (will also respond for missing parameters, etc.). If you send a media type it does not understand, it will send the 415 Unsupported Media Type.</p>

<h2 id="request-a-service-ticket">Request a Service Ticket</h2>

<h3 id="sample-request-1">Sample Request</h3>

<div class="highlight"><pre><code class="bash">POST /cas/v1/tickets/<span class="o">{</span>TGT id<span class="o">}</span> HTTP/1.0
 
<span class="nv">service</span><span class="o">={</span>form encoded parameter <span class="k">for </span>the service url<span class="o">}</span>
</code></pre></div>

<h3 id="sample-response-1">Sample Response</h3>

<h4 id="successful-response-1">Successful Response</h4>

<div class="highlight"><pre><code class="bash">200 OK
ST-1-FFDFHDSJKHSDFJKSDHFJKRUEYREWUIFSD2132
</code></pre></div>

<h4 id="unsuccessful-response-1">Unsuccessful Response</h4>
<p>CAS will send a 400 Bad Request. If an incorrect media type is sent, it will send the 415 Unsupported Media Type.</p>

<h2 id="logout">Logout</h2>

<div class="highlight"><pre><code class="bash">DELETE /cas/v1/tickets/TGT-fdsjfsdfjkalfewrihfdhfaie HTTP/1.0
</code></pre></div>


        </section>
      </div>

    <!-- FOOTER  -->
    <div id="footer_wrap" class="outer">
      <footer class="inner">
        <p>CAS is supported by the <a href="http://www.apereo.org/">Apereo Foundation</a>.</p>
      </footer>
    </div>
  </body>
</html>
